Skip to main content

FAQ & Troubleshooting

Getting Started​

  • How do I begin an OIDC integration project?

    • You will be assigned a Candescent Integration Project Manager via Marketplace. Your PM is your primary contact for the duration of the certification of your integration.

  • Can I test my integration before contacting Candescent?

    • Yes! Use the OIDC Toolkit to build and test your integration locally. The toolkit simulates Candescent's OIDC flow with the same endpoints and token format.

  • What information do I need to provide?

    • Complete the Setup Checklist with your application details, contacts, and redirect URIs.

    • Any information on your solution, or that you feel is relevant to the integration.

  • What is the typical integration process?

    • (Optional) Local development using the OIDC Toolkit

    • Initialization - Candescent PM provides relevant documentation, and answers any initial questions. Developer will then complete and return the Setup Checklist

    • Once the partner provides a completed Setup Checklist, the Candescent team will install the connection in our internal QA site for initial testing.

    • Initial QA validation using Candescent's standard test API app

    • Registration of your application and environments

    • Configuration of trust, security, and endpoints

    • Integration testing in FI environments

    • Certification and go-live

Technical Basics​

  • Which endpoints do I use?

    • Authorization endpoint: FI's branded domain (provided by your PM)

    • Token endpoint: api.candescent.com (centralized, backend only)

  • How do I get JWKS files?

    • Your assigned PM will provide JWKS files for each environment. There is no public JWKS URI.

  • What claims are supported?

    • Only standard OIDC claims (sub, iss, exp, iat, nonce, preferred_username, given_name, family_name, birthday, email, phone_number, auth_time)

  • Is there a UserInfo endpoint?

    • There is no standard OIDC /userinfo endpoint. All standard claims are included in the ID token. If you need additional user data, you can use the optional Institution-users endpoint.

Common Issues & Solutions​

  • Invalid redirect_uri:

    • Ensure the URI is registered, uses HTTPS, and matches exactly (no wildcards, no trailing slash differences).

  • State validation failed:

    • Store and validate the state parameter for CSRF protection.

  • Authorization code expired:

    • Exchange the code immediately (valid for 60–120 seconds).

  • Client authentication failed:

    • Verify credentials encoding and use client_secret_basic or client_secret_post.

  • Token signature validation fails:

    • Ensure you are using the correct JWKS file for the environment and that it is up to date.

  • JWKS key rotation:

    • Your PM will notify you and provide updated files when keys rotate.

Critical Timeouts​

  • Authorization code: 60–120 seconds

  • ID token: 5 minutes (extract claims immediately)

  • Access token: ~30 minutes

  • Session: ≤30 minutes

OIDC Toolkit Questions​

  • Where do I get the OIDC Toolkit?

    • Clone from GitHub: git clone https://github.com/candescent-dev/oidc-sso-toolkit.git
    • Or use the pre-built Docker image: docker pull ghcr.io/candescent-dev/oidc-sso-toolkit:latest

  • Do I need Docker to run the toolkit?

    • No. You can run it natively with Node.js 20+ for development. Docker is an optional alternative for quick testing without installing Node.js.

  • Why do my toolkit credentials expire after 15 minutes?

    • This is by design. The toolkit auto-generates new credentials to simulate real-world credential rotation. The page refreshes automatically.

  • Can I change the toolkit ports?

    • Yes. Edit sample-web-app/config.json to change frontend (default 8000) and backend (default 9000) ports.

  • How do I validate my integration with the toolkit?

Tips for Success​

  • Test locally with the OIDC Toolkit before connecting to Candescent environments

  • Extract ID token claims immediately after token exchange

  • Store credentials securely (never in code or logs)

  • Use HTTPS everywhere

  • Validate state and nonce parameters

  • Exchange authorization code for tokens immediately

Contact & Support​

For questions or support, reach out to your assigned Candescent Integration PM via Marketplace. Your PM will provide all necessary materials, guidance, and troubleshooting assistance.

References​